Skip to main content
Feedback

Boomi API Gateway installation - Linux

Perform the following tasks to complete the Boomi API Gateway installation on Linux.

  1. Verify that your computer meets the Gateway system requirements.

  2. Ensure you meet all Prerequisites.

  3. Download the Gateway installer.

  4. Set up Linux shared directories for the Gateway.

  5. Install the local Gateway on Linux.

  6. Install additional Gateway nodes. You must complete this task on each Windows machine that you add to the Gateway.

  7. Validate the Gateway installation.

note

Refer to the Gateway maintenance section if you need to adjust how the Gateway runs, change its default settings, or remove it.

tip

If you did not enable local storage during installation, it is recommended that you enable it to reduce unnecessary network traffic.

Prerequisites

To complete the installation, meet the following prerequisites:

  • Synchronize clocks and time zones.

    Ensure that the Gateway’s server clock, including central storage services (e.g., NFS), is synchronized regularly using something like NTP. If the clocks on the machines are not closely synchronized, you are likely to encounter problems with: the clustering protocol, accurate time recording for cross-node actions, and accurate handling of files on the shared file system.

    Ensure that all machines are set to use the same time zone. This includes the machines on which the Gateway nodes run, as well as file servers being used. Refer to your operating system's documentation for instructions on how to set your machines' time zone.

  • Consider failover and disaster recovery needs.

    If you have a multi-node Gateway behind a load balancer for which health checks are configured, in the event the head node fails, failover occurs automatically. The load balancer detects the failure and routes requests for both the Gateway and the Developer Portal to the other node(s).

    For information about backup and disaster recovery best practices for Gateways, review Best Practices for Run Time High Availability and Disaster Recovery Boomi Community article.

  • Configure NFS storage

    • Make sure the nfslock daemon is enabled at startup and is running on the NFS client nodes.

    • Make sure this central storage is mounted in the same path on all nodes and that the Broker account has write access to the path.

    • Make sure users and groups are correctly identified across mounts. Viewing file details in NFS mounted directories should display valid user and group names.

      • In NFSv4, this is often controlled by the idmapd daemon. Ensure this is enabled and running on each node and NFS server.

    • Leverage mount options that support binary execution via the share.

      • NFS client /etc/fstab example: vers=3,noatime,nodiratime,rw,hard,intr,bg,addr=nfsserver.domain.com

        • vers= - Specifies the NFS version the server must support. This option may not be necessary, depending on the client/server setup.

        • noatime - Disables "access time" tracking on files. This information is generally unnecessary to maintain and can waste nontrivial IO bandwidth.

        • nodiratime - This is the same as noatime except for directories.

        • rw - Read and write access is required by the runtime.

        • hard - Requires NFS client operations to complete. Not using this option may cause silent data corruption.

        • intr - Allows signals to interrupt NFS operations. This will prevent the system from hanging if the NFS server stops responding.

        • bg- Allows the system to start up even if the initial NFS mount fails. This will prevent the system from hanging on startup if the NFS server is not yet available.

        • addr= - The address used for servers with multiple IP subnets on the same interface. Usually this setting is not needed.

    • If you are using NFSv4, bind mounts are required in order to function.

      • NFS server /etc/fstab example: /data/boomi/exports/data/boomi none bind 0 0
      • NFS Server /etc/exports example: /exports <ipaddr/32>(rw,insecure,no_subtree_check,nohide,fsid=0,sync,no_root_squash)

Setting up Linux shared directories for a Gateway

Run the Gateway installer file on a machine that will share the installation directory and share the directory via NFS to other machines.

Perform the following steps:

  1. After downloading the Gateway installer (gateway_install.sh or gateway_install64.sh), run it on a machine that will eventually share the Gateway's installation directory.

  2. Share the directory via NFS to other machines, using the same installation directory name.

Installing a local Gateway on Linux

Install the downloaded Linux version of the local Gateway from a command line with the -c flag.

Gateways require the Java 11 JDK. The installer will install a private copy of Java 11 for the Gateway to use.

note

The private copy of the JDK is a complete JDK that is placed in your Gateway's jre directory. The private JDK will not interfere with a shared JDK (one that you, not the installer, installed). It is not integrated into browsers and does not write registry entries.

The installer gives you the option to select local directories for storing working data and temporary data. It is recommended that you select local directories. If you do select local directories, you must ensure that these directories exist before you run the installer. The installer does not create the directories for you.

note

If you choose not to use the GUI to install a Gateway, you can use the console mode option (-c) of the install4j installer.

Perform the following steps to install the Gateway:

  1. Locate the Gateway installer file that you saved to your machine.

    After the file is downloaded, the installation wizard can be run via a command line, which is recommended, or via the GUI.

  2. Do one of the following:

    • If you want to run the installer in console mode from a command line, run the file with the -c flag:

      sh /<path>/gateway_install64.sh -c

    • If you are using the GUI, double-click the install file (you might need to change the properties to allow executions: chmod +x gateway_install64.sh) or run the file from the command line without the command-only flag:

      sh /<path>/gateway_install64.sh

  3. If the installer cannot find the JRE on your machine, you are prompted to download it.

  4. On the Welcome page, click Next.

  5. On the User Information page:

    1. Select User Name and Password or Token, depending on how you want to authenticate the Gateway.

    2. Enter one of the following, depending on the option you selected:

    • your Boomi Enterprise Platform user name and password

    • a valid installer token

      Installer tokens can be generated when the Gateway installer is downloaded from the Gateway Setup dialog. A token is valid only for the account in which it was generated. Tokens expire after a set amount of time ranging from 30 minutes to 24 hours.

    1. Enter a name for the Gateway.

      This is the Gateway name that you see when you go to Configure Server > API Gateways. The name defaults to the local host name, but you can change it to something more familiar.

    note

    The following characters are reserved and cannot be used in the name: asterisk (*), backslash (\), caret (^), colon (:), dollar sign ($), greater than (>), less than (<), percent (%), pipe (|), question mark (?), quotation mark ("), slash mark (/), Yen sign (¥).

    1. Click Next.

    You connect to Boomi Enterprise Platform and your credentials are authenticated.

    If you specified a user name and password, the Accounts page is displayed.

    If you specified an installer token, the Select Directory for Symlinks page is displayed and you can skip to step 7.

  6. Optional: On the Accounts page:

    1. If your user name has access to multiple accounts, you see a list of accounts. Select the account to which this Gateway is associated. This step typically applies only to partners.

      If you are using the command line, each account name is followed by a number within square brackets, for example [123]. To select an account, enter its number.

    2. Click Next.

  7. On the Select Directory for Symlinks page, select the Don't create symlinks check box and click Next.

  8. On the Select Local and Local Temp Directories page:

    1. Select a local directory for storing the Gateway node’s working data.

    The directory that you select is stored in the Gateway’s Working Data Local Storage Directory property.

    1. Select a directory for storing the Gateway node’s temporary data.

    The directory that you select appears in the node’s bin/\*.vmoptions file as -Djava.io.tmpdir=<your_selected_directory>. If you do not set the local temporary directory, your default Java temp directory is used. The default directory is not recorded in the node’s bin/\*.vmoptions file.

    1. Click Next.

  9. On the Information page, review the installation settings and click Next.

    The installer installs all of the necessary files for your Gateway. You should see messages saying that the installer is retrieving the build number, extracting files, downloading Gateway files, and then finishing the installation.

  10. When the installation is complete, click Finish to start the Gateway.

You can view the Gateway online by going to Configure Server > API Gateways.

The installation log file is located in <gateway\_installation\_directory\>/tmp and its file name starts with i4j.

Installing additional Gateway nodes on Linux

Install additional Gateways on Linux by mounting the NFS directory containing the initial Gateway installation and then create a link in the scripts directory to the Gateway installation script. These steps must be executed on each machine that you are adding to the Gateway.

  1. On the machine on which you want to run the node, mount the NFS directory containing the initial Gateway installation (<gateway\_installation\_directory\>).

  2. Start the node manually by executing this command: <gateway_installation_directory>/bin/atom start

  3. Optional: For a SysV-style initialization where the node starts automatically at Linux startup, do the following:

    1. Create a link in the /etc/init.d scripts directory to the <gateway\_installation\_directory\>/bin/atom script.

    2. Configure the system to start this script by using existing SysV setup tools.

    note

    The specifics of this step might vary depending on your Linux distribution.

  4. After the new node is started, verify that it has joined the Gateway by looking in the <gateway\_installation\_directory/logs/<date\>.container.<machine\_IP\_address\>.log file for a message like this:

    INFO: Started <machine_IP_address> as CloudletAddress <machine_IP_address>:7800, initial cluster view: CloudletAddress <other_machine_IP_address:7800, CloudletAddress <machine_IP_address>:7800, ...

Validate the Gateway installation

Validate the Gateway installation using the link http://<gateway_node_name:<port_the_gateway_is_using>/_admin/status.

When the validation is successful, you receive the response shown below:

{
  "sync-manager" : {
    "healthy" : true
  },
  "rate-limit" : {
    "healthy" : true
  },
  "management" : {
    "healthy" : true
  },
  "gateway" : {
    "healthy" : true
  }
}
On this Page